%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
%%
%%    This file is part of ICTP RegCM.
%%    
%%    Use of this source code is governed by an MIT-style license that can
%%    be found in the LICENSE file or at
%%
%%         https://opensource.org/licenses/MIT.
%%
%%    ICTP RegCM is distributed in the hope that it will be useful,
%%    but WITHOUT ANY WARRANTY; without even the implied warranty of
%%    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
%%
%%::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Whatever method is chosen to download the code, we assume that you have now
on your working directory a new directory, named \verb=RegCM=.
That directory will be for the rest of this guide referred as 
\verb=$REGCM_ROOT= .

All the operations to build the model binaries will be performed in this
directory.

\section{Software requirements}

In order to configure and install the RegCM code, the following software are
needed:

\begin{enumerate}
    \item GNU build system (\verb=autoconf=, \verb=automake= and
        \verb=libtool= programs)
    \item GNU \verb=make= program
    \item Fortran 2008 compiler
    \item One in:
  \begin{enumerate}
    \item C compiler for the serial option (\verb=enable-mpi-serial= at
      configure)
    \item MPI3 Message Passing Library compiled with the above fortran compiler
     for parallel runs using multiple core single machines or cluster of
     machines (default).  Source code for the implementation code was tested
     with can be obtained at: \\
     {\bf http://www.open-mpi.org}
  \end{enumerate}
\item netCDF (\cite{Rew_90}) Format I/O library compiled with the above
  Fortran compiler with netCDF4 format support. Source code can be found from \\
  {\bf https://downloads.unidata.ucar.edu/netcdf/} \\
\end{enumerate}

Optional requirements strongly suggested are :

\begin{enumerate}
\item NCO netCDF Operators for manging netCDF file. Most Linux distribution
have this already packed, and you should refer to your System Administrator or
OS Software Installation manual to obtain it. Source code is at: \\
{\bf http://nco.sourceforge.net}
\item CDO Climatic data Operators for managing netCDF file. Most Linux
distribution have this already packed, and you should refer to your System
Administrator or OS Software Installation manual to obtain it.
Source code is at: \\
{\bf https://code.mpimet.mpg.de/projects/cdo }
\item A Scientific Plotting and Data Analysis Software such as:
\begin{itemize}
\item Python Xarray \\ {\bf https://xarray.dev/ }
\item Iris \\ {\bf https://scitools-iris.readthedocs.io/en/stable/ }
\end{itemize}
\item Historically supported software, now not actively maintained, are:
\begin{itemize}
    \item IGES GrADS Graphical Analysis and Display System. Convenient helpers
are packed in RegCM to use GrADS with RegCM netCDF output files.
Binaries and source code can be obtained from \\
        {\bf https://github.com/j-m-adams/GrADS}
    \item NCL, NCAR CISL Command Language. The NCL can read netCDF output files, and sample scripts can be found in the {\em Tools/Scripts/NCL} directory.
Binaries and source code can be obtained from \\
{\bf http://www.ncl.ucar.edu}
\end{itemize}
\item A quick viewer for netCDF files like NcView: \\
{\bf https://cirrus.ucsd.edu/ncview/}
\end{enumerate}

A script is shipped in the RegCM codebase in the Tools directory to help
user compile and install {\bf required} packages, and its usage is detailed in
chapter $\ref{Appendice}$.

\section{Configuring build}

The RegCM Version 5 is configured by a configure script, which will select
the known working configuration for the supported architectures.

Currently tested and supported configurations (OS/Compiler) are:

\begin{enumerate}
\item Linux with GNU gfortran compiler version $\ge 9.0$
\item Linux with Intel\texttrademark ifort/ifx compiler version $\ge 18.0$
\item Linux with NVIDIA\texttrademark nvfortran compiler version $\ge 21.0$
\item Mac OsX\texttrademark with gfortran compiler $\ge 6.0$ from Homebrew
\end{enumerate}

The 5.0 version of the RegCM model relies on the standard GNU autotools to
configure and build the model code.

To create the \verb=configure= script, the user must change into the 
working directory \verb=$REGCM_ROOT= and run the command:

\begin{Verbatim}
$> cd $REGCM_ROOT
$> autoreconf -f -i
\end{Verbatim}

or the same through the packaged bootstrap script:

\begin{Verbatim}
$> cd $REGCM_ROOT
$> ./bootstrap.sh
\end{Verbatim}

This command must be run any time modifications to the \verb=configure.ac= or
the \verb=.m4= files is performed.
If the above fails, the most probable problem is the missing or outdated
version of GNU build tools on the target system. Please check with your
system administrator on how to install them
({ \bf https://www.gnu.org/software/automake/ }).

The next step is to run the \verb=configure= script giving as arguments the
chosen compilers:

\begin{Verbatim}
$> cd $REGCM_ROOT
$> ./configure # or, for intel compiler OneApi: ./configure CC=icx FC=ifx
\end{Verbatim}

To know the list of arguments that can be given to the configure script, the
script can be launched with the \verb=--help= command line argument.

\begin{Verbatim}
$> ./configure --help
\end{Verbatim}

The useful arguments to successfully build the model are:

\begin{Verbatim}
  --with-netcdf           Path to NetCDF installation (default: NETCDF
                          environment)
  --with-hdf5             Path to HDF5 installation (default: HDF5
                          environment)
  --with-szip             Path to SZIP installation (default: SZIP
                          environment)
  CC=         C compiler command
  CFLAGS=     C compiler flags
  LDFLAGS=    linker flags, e.g. -L<lib dir> if you have libraries in a
              nonstandard directory <lib dir>
  LIBS=       libraries to pass to the linker, e.g. -l<library>
  CPPFLAGS=   (Objective) C/C++ preprocessor flags, e.g. -I<include dir> if
              you have headers in a nonstandard directory <include dir>
  CPP=        C preprocessor
  FC=         Fortran compiler command
  FCFLAGS=    Fortran compiler flags
  MPIFC=      MPI Fortran compiler command
\end{Verbatim}

\subsection{Model configuration at build stage}
\label{modconf}

\begin{enumerate}
\item Enable debug
\begin{Verbatim}
  --enable-debug     Enable debugging flags and per processor log file
\end{Verbatim}
If enabled, the model will be compiled using debug flags for the compiler,
which will allow the use of a debugger such as gdb. More diagnostics will
also be generated during model run.
The default is to build production binaries with all optimization flags
turned on.

\item Serial code using stub MPI library
\begin{Verbatim}
  --enable-mpiserial Use the included MPI replacement library for single
                     processor
\end{Verbatim}
The model is coded to use an MPI2 library to run in parallel mode using
multiple cores/processors or run on a cluster. To enable instead a serial
compilation option, a stub MPI library with empty callbacks needs to be
compiled and linked to the executable.
The RegCM team strongly suggest to build MPI enabled model also on standalone
systems, to take advantage of the multicore capabilities of any modern
processor.
\item CLM option
\begin{Verbatim}
  --enable-clm       Supply this option if you plan on using CLM option.
\end{Verbatim}
This option switches off the default Land model of RegCM (derived from BATS1e),
and enables the use of the Community Land Model V3.5 inside RegCM. The default
is to use the RegCM BATS Land Model.
\item CLM 4.5 option
\begin{Verbatim}
  --enable-clm45     Supply this option if you plan on using CLM45 option.
\end{Verbatim}
This option switches off the default Land model of RegCM (derived from BATS1e),
and enables the use of the Community Land Model V4.5 inside RegCM. The default
is to use the RegCM BATS Land Model, but ICTP is strongly suggesting this as
the default surface model option to be used on CORDEX projects,
\item OASIS option
\begin{verbatim}
  --enable-oasis     Supply this option if you plan on using OASIS
                     option.
\end{verbatim}
This option enables the OASIS-related processes inside RegCM. During the run,
these sections of the code allow communication between RegCM and the other
components of a coupling system through the OASIS interface module. The default
is not to use OASIS.
Enabling this option requires OASIS to be installed. The installation directory
must be supplied, as well as the used type of communication technique
(\verb=MPI1= or \verb=MPI2=; the default is \verb=MPI1=).
The corresponding arguments are shown below.
\begin{verbatim}
  --with-oasis-path  Path to OASIS3-MCT installation (require
                     --enable-oasis) [default:
                     ~/oasis3-mct/compile_oa3-mct]
  --with-oasis-comm  Communication technique used in OASIS3-MCT (require
                     --enable-oasis) [default: MPI1]
\end{verbatim}
\end{enumerate}

\section{Build the model executables}

Now that everything is hopefully configured, you may use the \verb=make=
program to build executables.

\begin{Verbatim}
$> make version
$> make
\end{Verbatim}

This target will builds all model parts. 
The compilation is started in the whole model tree (PreProc, Main and PostProc).
Lot of messages will appear on screen, abd at the end all executables are built
int the source directories.
To copy them to a \verb=bin= directory in the model root or into a \verb=bin=
directory in the path specified with the prefix argument to the \verb=configure=
script, esplicitly issue the command:

\begin{Verbatim}
$> make install
\end{Verbatim}

Congratulations! You can now go to next step and run a test simulation.
